home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / cat3 / ftw.3 < prev    next >
Encoding:
Text File  |  1993-03-03  |  3.0 KB  |  133 lines
  1.  
  2.  
  3.  
  4. FTW(3)              MINTLIB LIBRARY FUNCTIONS              FTW(3)
  5.  
  6.  
  7. N✓NA✓AM✓ME✓E
  8.        ftw - walk a file tree
  9.  
  10. S✓SY✓YN✓NO✓OP✓PS✓SI✓IS✓S
  11.        #include <ftw.h>
  12.  
  13.        int ftw(char *path, int (*fn)(char *, struct stat *, int), int depth);
  14.  
  15. D✓DE✓ES✓SC✓CR✓RI✓IP✓PT✓TI✓IO✓ON✓N
  16.        ftw recursively descends the directory hierarchy rooted in
  17.        path.  For each object in the  hierarchy,  ftw  calls  the
  18.        user-supplied function fn, passing it a pointer to a null-
  19.        terminated character string containing  the  name  of  the
  20.        object,  a pointer to a stat structure containing informa-
  21.        tion about the object, and an integer.  Possible values of
  22.        the integer, defined in the <ftw.h> header file, are FTW_F
  23.        for a file, FTW_D for a directory, FTW_DNR for a directory
  24.        that  cannot  be  read, and FTW_NS for an object for which
  25.        stat could not successfully be executed. If the integer is
  26.        FTW_DNR,  descendants  of  that directory will not be pro-
  27.        cessed. An example of an object that would cause FTW_NS to
  28.        be  passed  to fn would be a file in a directory with read
  29.        but without execute (search) permission.
  30.  
  31.        ftw visits a directory before visiting any of its  descen-
  32.        dants.
  33.  
  34.        The  tree traversal continues until the tree is exhausted,
  35.        an invocation of fn returns a nonzero value, or some error
  36.        is detected within ftw (such as an I/O error). If the tree
  37.        is exhausted, ftw returns zero. If fn  returns  a  nonzero
  38.        value,  ftw  stops its tree traversal and returns whatever
  39.        value was returned by fn. If  ftw  detects  an  error,  it
  40.        returns -1, and sets the error type in errno.
  41.  
  42.        ftw  uses  one file descriptor for each level in the tree.
  43.        The depth argument limits the number of  file  descriptors
  44.        so  used.  If depth is zero or negative, the effect is the
  45.        same as if it were 1. Depth must not be greater  than  the
  46.        number  of  file  descriptors currently available for use.
  47.        ftw will run more quickly if depth is at least as large as
  48.        the number of levels in the tree.
  49.  
  50. S✓SE✓EE✓E A✓AL✓LS✓SO✓O
  51.        s✓st✓ta✓at✓t(✓(3✓3)✓)
  52.  
  53. N✓NO✓OT✓TE✓ES✓S
  54.        Note that MiNT limits each process to 32 file descriptors.
  55.        Since three are normally used for standard  input,  output
  56.        and error output, only few remain.
  57.  
  58.        C library functions like this are usually only found after
  59.        a similar version has already been written by the program-
  60.        mer.
  61.  
  62.  
  63.  
  64. MiNT docs 0.1              3 March 1993                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. FTW(3)              MINTLIB LIBRARY FUNCTIONS              FTW(3)
  71.  
  72.  
  73. B✓BU✓UG✓GS✓S
  74.        Because  ftw is recursive, it is possible for it to termi-
  75.        nate with a memory fault when applied to  very  deep  file
  76.        structures.
  77.  
  78.        Symbolic  links are reported to the user-supplied function
  79.        as FTW_F.
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130. MiNT docs 0.1              3 March 1993                         2
  131.  
  132.  
  133.